/* Copyright (c) 2007  Peter Palotas
 *  
 *  This software is provided 'as-is', without any express or implied
 *  warranty. In no event will the authors be held liable for any damages
 *  arising from the use of this software.
 *  
 *  Permission is granted to anyone to use this software for any purpose,
 *  including commercial applications, and to alter it and redistribute it
 *  freely, subject to the following restrictions:
 *  
 *      1. The origin of this software must not be misrepresented; you must not
 *      claim that you wrote the original software. If you use this software
 *      in a product, an acknowledgment in the product documentation would be
 *      appreciated but is not required.
 *  
 *      2. Altered source versions must be plainly marked as such, and must not be
 *      misrepresented as being the original software.
 *  
 *      3. This notice may not be removed or altered from any source
 *      distribution.
 *  
 *  
 *  $Id: IMultiDictionary.cs 19 2007-08-15 13:14:32Z palotas $
 */
using C5;

namespace Plossum.Collections
{
    /// <summary>
    /// Represents a generic collection of key/value pairs allowing multiple objects with the same key to
    /// be stored.
    /// </summary>
    /// <typeparam name="TKey">The type of keys in the dictionary.</typeparam>
    /// <typeparam name="TValue">The type of values in the dictionary.</typeparam>
    public interface IMultiDictionary<TKey, TValue> : IDictionary<TKey, ICollection<TValue>>
    {
        /// <summary>
        /// Adds an element with the provided key and value to the <see cref="T:IMultiDictionary`2"/>. 
        /// </summary>
        /// <param name="key">The object to use as the key of the element to add.</param>
        /// <param name="value">The object to use as the value of the element to add.</param>
        /// <exception cref="System.ArgumentNullException"><paramref name="key"/> is a null reference (<b>Nothing</b> in Visual Basic).</exception>
        /// <exception cref="System.NotSupportedException">The <b>IMultiDictionary</b> is read-only.</exception>
        void Add(TKey key, TValue value);

        /// <summary>
        /// Removes the element with the specified key and value from the <see cref="T:IMultiDictionary`2"/>.
        /// </summary>
        /// <param name="key">The key of the element to remove.</param>
        /// <param name="value">The value of the element to remove.</param>
        /// <returns><b>true</b> if the element was successfully removed; otherwise, <b>false</b>.</returns>
        bool Remove(TKey key, TValue value);

        /// <summary>
        /// Returns the number of elements in the <b>IMultiDictionary</b> with the specified <paramref name="key"/>.
        /// </summary>
        /// <param name="key">The key to search for.</param>
        /// <returns>the number of elements in the <see cref="T:IMultiDictionary`2"/> with the specified <paramref name="key"/>.</returns>
        int KeyCount(TKey key);
    }
}
